Repository navigation
Framework contracts use direct en-US prose - #580
Open
Marius Storhaug (MariusStorhaug) wants to merge 4 commits into
Open
Marius Storhaug (MariusStorhaug) wants to merge 4 commits into
Marius Storhaug (MariusStorhaug) wants to merge 4 commits into
Conversation
Open
6 tasks done
Super-linter summary
All files and directories linted successfully For more information, see the GitHub Actions workflow run Powered by Super-linter |
Contributor
There was a problem hiding this comment.
🟢 Approved
No active review issues block these documentation-only clarity and consistency updates.
No open issues 🎉
What changed in this PR
This documentation-only PR makes Process-PSModule’s framework specifications and references more direct and consistent with en-US prose. It preserves existing workflow contracts and release policy; module authors need no code, settings, or caller-workflow changes.
Changes:
- Shortens descriptions of framework architecture, versioning, and colocation.
- Clarifies reference-page wording for settings, workflow interfaces, pipeline stages, and repository standards.
- Standardizes spelling and corrects grammar without changing executable code.
| File | Description |
|---|---|
docs/content/specification/principles-and-practices.md |
Clarifies linear versioning and colocation principles. |
docs/content/specification/index.md |
States the intended maintainer audience directly. |
docs/content/specification/design.md |
Simplifies architecture and settings-contract descriptions. |
docs/content/reference/workflow-inputs.md |
Clarifies caller-interface and credential-control wording. |
docs/content/reference/versioning.md |
Shortens version-category and compatibility explanations. |
docs/content/reference/settings.md |
States supported settings formats and the default path directly. |
docs/content/reference/repository-standard.md |
Clarifies scope and baseline requirements; corrects grammar and spelling. |
docs/content/reference/powershell-module-standard.md |
Uses en-US spelling and simplifies design-principle explanations. |
docs/content/reference/pipeline-stages.md |
Streamlines job descriptions, report wording, and failure statements. |
Review effort: Balanced
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
November 4, 2026 14:43
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Framework maintainers get shorter, direct en-US specification and reference prose. The existing requirements, workflow interfaces, examples, release policy, and publication guarantees stay unchanged. Module authors do not need to change code, settings, or caller workflows.
Changed: Framework guidance states existing contracts directly
The design uses
behaviorand removes the subjective phrasesensible defaults. The principles describe linear version history and colocation without first-person narration. Reference descriptions use clear subjects and present tense. The patch-version description states intended compatibility instead of the absoluteno riskpromise, under the explicit handback in #562. This is a wording change, not a SemVer policy change or evidence of new runtime enforcement. Procedures stay imperative.All eleven assigned pages were read in full before editing. Nine pages change; the normative specification and scenario matrix are intentional no-change reviews. No proposal-only artifact-root section is imported. The protected fingerprint mechanism and its related automation claims remain unchanged for #577. The mock-policy and major-policy decisions remain separate.
Technical details
Source and delivery identities
PSModule/Process-PSModule@64ffb1d87f86bd5d487891fdb140b78385a00531.PSModule/Process-PSModule@b8a2e4ff2056409f89289a3209f5b08c3ad42031, branchframework-contract-prose, base branchmain.9ba4a606ca4a6aa2e460b8e994c9fdc9eff82631. Small follow-ups are769fad09b875efec70c2fc6199f9a9c53297990f,30d6bc69fcf8ff9c0673e8c055a3b35927f69276, andb8a2e4ff2056409f89289a3209f5b08c3ad42031. No old proposal or first-pass PR is amended.2001551566898e59efc764e68450c2238667d607oncomplete-artifact-path-isolation; its proposal and owner branch are untouched. The recorded issue handback is the authority for existing pipeline prose, not permission to import that proposal's additions.Writing sources
The fixed baseline is
MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs: Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, and the applicable specification/design/reference/standard templates. Their artifact distinctions remain intact; no template scaffolding is added.The official STE overview, FAQ, and relevant Issue 9 rules were read. Issue 9 rules 3.2, 3.6, 4.1-4.2, and 6.1-6.6 informed tense, active voice, short complete sentences, and descriptive paragraphs. The locally retained official PDF MD5 is
9c720341c350ed77943b2c73d01c716f, matching the official record. No manual content is republished. The bounded review and scans do not certify full ASD-STE100 conformance.Complete reviewed scope and before/after evidence
All paths below are under
docs/content/. The before text comes from the immutable PR base above; the after text is in the pushed candidate. Natural Language supplies en-US and direct language, the Documentation Model preserves normative contracts without implying implementation, and STE guidance supplies short complete sentences and active descriptive language.specification/index.mdaimed at people maintaining Process-PSModule itselftofor maintainers of Process-PSModulenormally, and both reader links remain.specification/spec.mdThe pipeline MUST compile the PowerShell module source code into a module artifactspecification/design.mdbehaviourtobehavior;everything else uses sensible defaultstoOther settings use defaultsspecification/principles-and-practices.mdwe only maintain a single linear ancestry of versionstomaintains one linear version history2.1.3security fix does not go to 1.x. Dependency declarations and parameter descriptions retain their colocation examples and exact code tokens.reference/pipeline-stages.mdreport that is used by ... evaluate the resultstoreport that ... uses to evaluate the test resultsreference/powershell-module-standard.mdresource or behaviour groupstoresource or behavior groups;knobstoinputsreference/repository-standard.mdoperates at the same altitude astocomplements;then pointstothen pointreference/scenario-matrix.mdreference/settings.mdBy default, it will look fortoThe default path is.github/PSModule.ymldefault, authorable/runtime boundary, and complete settings/default tables and example.reference/versioning.mdwith no risk of breaking functionalitytointended to preserve compatibilityreference/workflow-inputs.mdFor how to wire it uptoFor caller configurationThe two no-change Git blob identities are exact on base and head:
specification/spec.mdis5755abf2797a699e0ef0846ac2521cb1fb90b2bb;reference/scenario-matrix.mdisd9c5490f5379fe94adf94df6ac349dfc0b82b8d1.Preservation results
Pre-edit session evidence records concrete original text, its expected wording property, and source-backed acceptance before repository edits. Nine intended wording cases fail on the original source; all eleven page-level cases pass on the pushed candidate, including the two no-change cases. The session-only comparison reports zero preservation failures.
The protected passages include the public-API major policy, latest-version support policy, API-fingerprint section, both related automation-claim paragraphs, mocked-environment requirement, module-owned boundary-mock rule, linear maintenance policy, version resolution/publication sequence, pipeline runtime contract, root-only phase/discovery rules, framework-generated coverage guarantee, and stable publication/cleanup section. The fingerprint source is blob
ee2eafdd83405ab42da7a25aa5f6e9ff367e6d5e, base lines 127-155; its section SHA-256 remainsfb098e0eea00a129b7f87f13806acc104de6ad47439769355d2d2c8fcf824e23.The selected main pipeline page contains neither a Consumer artifact root section nor a
<WorkingDirectory>/.PSModule/token. Both remain absent. Existing paths are unchanged; no unmatched proposal content or runner-only exception is added, removed, or reinterpreted.Existing checks and accepted review
The existing repository Markdown configuration passes on all eleven explicit paths, before edits and on the completed source:
Result: 11 files, 0 issues. An initial Windows wildcard invocation selected only seven files; it was corrected to the explicit eleven-file command above, not treated as full-scope evidence.
The existing site command,
zensical build --cleanfromdocs, passes before and after the changes withNo issues found.git diff --checkpasses for the complete base-to-head change. The session-only preservation/wording command also passes at exact pushed headb8a2e4ff2056409f89289a3209f5b08c3ad42031.No standalone documentation-link checker is present in this main tree. The link-check scripts named in the MSX Markdown standard belong to the MSX docs repository, not this repository. No dependency was installed; no enforcement tool, prose/inventory/implementation-shape snapshot test, or repository audit document is added.
All six applicable hosted checks succeed at the exact candidate: Docs Build and Lint, repository Lint code base, CodeQL, Actions analysis, and Copilot review. Publication is skipped as expected on the draft. Copilot review was explicitly requested with the CLI-supported
@copilotvalue. Its completed review isAPPROVEDatb8a2e4ff2056409f89289a3209f5b08c3ad42031, with no inline comments or active issues. Docs run, repository lint run, and hosted review run retain the results.The coordinating parent also accepted the content at this exact head after independently reading all nine changed-page diffs and comparing all eleven pages. Its comparison preserves headings, inline literals, destinations, fences, table rows, modality sequences, the fingerprint section and related automation text, and mocked-environment requirements. This records content acceptance only; the PR remains draft and no readiness or merge action is authorized.
Alignment and residual decisions
The delivery issue's pre-edit read, expectations, baseline, small-commit wording, ownership-recheck, and local current-head validation steps are complete. The scoped convergence sweep covered open
documentation-writing-alignmentissues, the protected follow-ups, the eleven owned paths, and the disjoint first-pass PR paths. No additional issue is closed by this bounded prose change.Residual decisions are precise: #577 reconciles the unsupported fingerprint mechanism and related claims with the real resolver after #359/#524 producer decisions; #563 decides mock policy by test category; #573 decides bootstrap-core versus complete-public-API major policy. No runtime, framework upgrade, site redesign, release-label, readiness, merge, or automation change is made. This PR stays draft.
Related references